﻿@page "/docs/extensions/autocomplete"

<Seo Canonical="/docs/extensions/autocomplete" Title="Blazorise Autocomplete component" Description="Learn to use and work with the Blazorise Autocomplete component, which provides suggestions while you type into the field." />

<DocsPageTitle Path="Extensions/Autocomplete">
    Blazorise Autocomplete component
</DocsPageTitle>

<DocsPageLead>
    The <Code>Autocomplete</Code> component offers simple and flexible type-ahead functionality.
</DocsPageLead>

<DocsPageParagraph>
    <LicenseLimitationAlert LimitText="@($"{Licensing.BlazoriseLicenseProvider.DEFAULT_UNLICENSED_LIMIT_AUTOCOMPLETE_MAX_ROWS} items")" />
</DocsPageParagraph>

<DocsPageParagraph>
    The <Code>Autocomplete</Code> component provides suggestions while you type into the field. The component is in essence
    a text box which, at runtime, filters data in a drop-down by a <Code>Filter</Code> operator when a user captures a value.
    You may also enable <Code>FreeTyping</Code> and <Code>Autocomplete</Code> can be used to just provide suggestions based on user input.
</DocsPageParagraph>

<DocsPageSubtitle>
    Quick Installation
</DocsPageSubtitle>

<Alert Color="Color.Info" Visible>
    <AlertDescription>
        The Autocomplete extension is part of the <Code>Blazorise.Components</Code> NuGet package.
    </AlertDescription>
</Alert>

<DocsPageSection>
    <DocsPageSectionHeader Title="Step 1: Download from NuGet">
        Install extension from NuGet:
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="ComponentsNugetInstallExample"></DocsPageSectionSource>
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Step 2. Define Usings">
        In your main <Code>_Imports.razor</Code> add:
    </DocsPageSectionHeader>
    <DocsPageSectionSource Code="ComponentsImportExample"></DocsPageSectionSource>
</DocsPageSection>

<DocsPageSubtitle>
    Examples
</DocsPageSubtitle>

<DocsPageSection>
    <DocsPageSectionHeader Title="Searching single value">
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Searching multiple values">
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteMultipleExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteMultipleExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Searching with data on demand (ReadData)">
        Frequently, you'll want to read data on demand rather than loading everything into memory at startup. You can do it with the <Code>ReadData</Code> API.
        It will provide you with enough information for you to call an external data-source, which will return new data, which you can then reassign to the <Code>Data</Code> parameter.
        <Alert Color="Color.Info" Visible>
            <AlertDescription>
                <Strong>Note:</Strong> Make sure to check the <Code>CancellationToken</Code> before commiting your values to <Code>Data</Code>. This will make sure to avoid race conditions and keep your <Code>Data</Code> updated according to the user's last key stroke.
            </AlertDescription>
        </Alert>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteReadDataExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteReadDataExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Extending with custom item content">
        Customize the way you display the Autocomplete items by providing <Code>ItemContent</Code>.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteItemContentExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteItemContentExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Suggesting already selected items && Checkbox support">
        You can use <Code>SuggestSelectedItems</Code> to suggest already selected items, and optionally use <Code>SuggestMultipleCheckbox</Code> to additionally add checkbox selection.
        <Strong>Note: </Strong> Make sure to set <Code>CloseOnSelection</Code> to false if you want to keep the dropdown open whenever an item is selected.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteSuggestMultipleCheckboxExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteSuggestMultipleCheckboxExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Highlight search text">
        Autocomplete <Code>HighlightSearch</Code> is a feature that allows you to highlight the search text that you have entered in a dropdown list of items. When you start typing in the search field, the dropdown list of items will automatically be filtered to show only the items that match the search text. The search text will also be highlighted in the dropdown list of items, so that you can easily see which items match your search. This can be a useful feature when you are trying to find a specific item in a long list of items, as it allows you to quickly locate the item you are looking for.
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteHighlightExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteHighlightExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Virtualize">
        <Paragraph>
            Blazorise Autocomplete's Virtualize feature allows for loading data on demand while scrolling, which improves the performance of the component when working with large datasets. With Virtualize, the Autocomplete component only loads the items that are currently visible in the list, and as the user scrolls, more items are loaded in the background. This allows for a much faster and smoother user experience, especially when working with large lists of items.
        </Paragraph>
        <Paragraph>
            This feature can be easily enabled by setting the <Code>Virtualize</Code> property to <Code>"true"</Code> on the Autocomplete component.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteVirtualizeExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteVirtualizeExample" />
</DocsPageSection>

<DocsPageSection>
    <DocsPageSectionHeader Title="Virtualize with ReadData">
        <Paragraph>
            Blazorise Autocomplete's <Code>Virtualize</Code> and <Code>ReadData</Code> features work together to handle large datasets efficiently.
            The <Code>ReadData</Code> event allows you to load only the data needed for the current interaction, without loading the entire dataset into memory.
            Meanwhile, the <Code>Virtualize</Code> property ensures that only the visible items are rendered in the DOM, significantly improving performance when working with large lists.
        </Paragraph>
        <Paragraph>
            In the provided example, the dataset is represented using <Code>IEnumerable</Code> for simplicity, but in real-world scenarios, you would typically use <Code>IQueryable</Code>.
            This allows for true deferred execution, ensuring only the required data is fetched and processed.
        </Paragraph>
        <Paragraph>
            To enable <Code>Virtualize</Code> with <Code>ReadData</Code>, you must also set the <Code>TotalItems</Code> property.
            The <Code>TotalItems</Code> value represents the total count of items in your dataset and is required for proper virtualization.
        </Paragraph>
    </DocsPageSectionHeader>
    <DocsPageSectionContent Outlined FullWidth>
        <AutocompleteVirtualizeAndReadDataExample />
    </DocsPageSectionContent>
    <DocsPageSectionSource Code="AutocompleteVirtualizeAndReadDataExample" />
</DocsPageSection>


<ComponentApiDocs ComponentTypes="[typeof(Autocomplete<,>)]" />